The MetaKit Library API

This document describes the Application Programming Interface (API) for MetaKit - a C++ class library for storage and transport of structured data.  For the latest news, please check the MetaKit web pages on internet at:

.   http://purl.net/meta4/metakit

Reference

1. Class Reference

2. Source Files

3. Advanced Topics

Copyright ©  1996 Meta Four Software. All rights reserved.

This document has been automatically generated from comments in the MetaKit source code (with "Autoduck"). It is available in HTML, RTF, and WINHELP format.


1. Class Reference

Several classes listed below are only used internally, they are listed here to clarify some of the most essential internal details. Many other implementation classes have been omitted for brevity.

If you are looking at this documentation to familiarize yourself with the MetaKit library API, you should start with the classes contained in the "k4view.h" file: the core classes are c4_View, c4_Row, and c4_Storage, with additional details in c4_Cursor and c4_RowRef. You should also look at c4_Property and the classes derived from it, which define a couple of basic datatypes.

If you want to delve into the implementation: the c4_Sequence container is an essential base class of the library, as are the c4_Handler data representation handlers and the c4_Persist persistent storage manager.

c4_Bytes

c4_Column

c4_Cursor

c4_DoubleProp

c4_DoubleRef

c4_Field

c4_FloatProp

c4_FloatRef

c4_Handler

c4_IntProp

c4_IntRef

c4_Persist

c4_Property

c4_Reference

c4_Row

c4_RowRef

c4_Sequence

c4_Storage

c4_Strategy

c4_StringProp

c4_StringRef

c4_Table

c4_View

c4_ViewProp

c4_ViewRef


2. Source Files

Header files

CONFIG.H - Wrapper for the compatibility headers

CONFWM.H - Public Windows/MFC configuration header

DERIVED.H - Derived sequences declarations

FIELD.H - Field declarations

FIX.H - Header to fix compatibility problems

FORMAT.H - Format handler declarations

HANDLER.H - Data handler declarations

HEADER.H - First header in sources

MFC.H - Microsoft Foundation Classes

MSVC.H - Microsoft Visual C++

PERSIST.H - Persistence declarations

STORE.H - Storage declarations

STRAT.H - Strategy declarations

TABLE.H - Table declarations

VIEW.H - View declarations

VIEWX.H - Auxiliary view declarations

WIN.H - All flavors of Windows and DOS

Inline definitions

FIELD.INL - Field inline declarations

TABLE.INL - Table inline declarations

VIEW.INL - View inline declarations

Implementation files

DERIVED.CPP - Derived sequence implementation.

FIELD.CPP - Field implementation.

FORMAT.CPP - Format handler implementation.

HANDLER.CPP - Data handler implementation.

MFC.CPP - MFC support classes

PERSIST.CPP - Persistence implementation.

STORE.CPP - Storage implementation.

TABLE.CPP - Table implementation.

VIEW.CPP - View implementation.

VIEWX.CPP - Auxiliary View implementation.


3. Advanced Topics

Attached and unattached views

Implementation limits

Performance considerations

Where to define properties


Attached and unattached views

Views and storage objects interact in very specific ways.

This is caused by the fact that views are inherently heterogenous - they can contain rows with differ in their properties / structure as well as in contents. Storage objects are homogenous, as they use a simple tree-based data description.

As a consequence, every loaded data structure can be manipulated as a view, but not every view can be saved as is into a storage object.

The approach taken by MetaKit is to treat views differently, depending on whether they are associated with a storage object or not.  When a view is constructed programatically (using the various view/row/property operators), it is "unattached".  When a view is created from a data file using a storage object, it is "attached".  This distinction is maintained until the view is destroyed, even if new rows and/or properties are added to it.

Note that adding rows to an attached view will alter the stored data, but that adding new properties will NOT. This is in fact a "feature", because it allows you to store additional "cached" information in each row at run time which never gets saved. Such cached information can be anything, including subviews.

There is no need to "store" an attached view into a storage object after changes, since changes to it automatically gets saved to file (if committed, that is).

The important special case is c4_View::Store.  When an unattached view is passed to Store, it will be copied into the storage object, using "deep copy" semantics (this can be expensive if the view is very large). To accomplish this, c4_View::Store scans the view structure and determines a homogenous data structure which most closely matches the (possibly heterogenous) view.  Rows are stored as having all properties occurring in all sub-rows (set union), in a common order.

Please note that the unattached view passed to Store remains unaffected. This may be confusing at first, but the other approach would actually be much more problematic, since the view structure and anything (anywhere!) pointing into that view might be affected in unintuitive ways - simply by storing it...

As a general rule, it is usually more convenient to work with attached views. This means that you should write

.   c4_View view = storage.View("name");

as early as possible, and stick with that view throughout your code. Note that views act like pointers, so if you pass copies of them around you will still be using the attached views.

If you need to work with a new view and store it in an existing file, you can use either

.   c4_View view = storage.GetAs("name[prop1:S,prop2:S]");

to start off with an attached view of the specified structure, or you can set up an unattached view first and "attach" it later with

.   view = storage.Store("name", view);

The optional assignment shown here causes the view to refer to the new attached version. Because of the copying of c4_View::Store, this approach adds more overhead and should be avoided when adding large amounts of data.


Implementation limits

MetaKit has been designed to run on a wide range of computers. Some of the supported platforms pose more restrictions than others.

The most restrictive platform is evidently small-model MS-DOS.  In that environement, the 64 Kb data segment memory contraints will severely limit the size of data files which can be manipulated.

On MS-DOS and 16-bit Windows, the MFC-based implementation has some array size limits which affect MetaKit.  As a result, views are usually limited to at most 8191 rows.  But since views can be nested, the total size of data files can far exceed 8191 rows.  A good example of this is the 16-bit CatFish disk catalog browser built with MetaKit: each catalog can store tens (maybe hundreds) of thousands of file entries - provided that no single directory contains over 8191 files.

With MS-DOS, available memory (of the 640 Kb) will be the limiting factor.

In 32-bit environments, there are no significant size limitations. As a test 500,000 records have succesfully been stored in a view (with 3 properties per record, this took 30 seconds on a P5/166 with Windows 95...).


Meta Four Software

CONTACT INFORMATION

.    Jean-Claude Wippler          mailto:jcw@meta4.nl

.

.    Meta Four Software             http://purl.net/meta4

.    Meekrap oord 6

.    3991 VE, Houten                 fax:+31 30 635 2337

.    The Netherlands


Performance considerations

When carefully used, MetaKit can offer extremely high performance.

As with any non-trivial framework, knowing which approach performs best may take some experimentation.  Here are some notes to ease this task.

One of the most effective optimizations with MetaKit is a rather surprising one: when you are iterating through the information and getting or setting property values, you should try to organize the loops in such a ways that the inner loop iterates over ROWS while the outer loop selects the PROPERTIES. This may appear counter-intuitive - but it can be explained by the fact that MetaKit organizes its data by columns, not by rows.  The effects can be stunning, because such tight inner loops often let modern processors take much better advantage of built-in cache hardware.

Several other aspects of MetaKit are still evolving, and have in some cases not been optimized at all.  The following tips are known to improve performance in the current version:

1) Avoid creating/destroying c4_Row objects inside a loop if possible.
 2) Setting strings properties can be slower in (large) attached views.
 3) Pre-allocate when storing many rows (SetSize + Set's are faster than Add's).
 4) Open/commit performance is proportional to the number (not size) of subviews.
 5) Storing an unattached view (see elsewhere) requires more temporary memory.
 6) The c4_View::Search operation is not very smart, it still uses a linear scan.
 7) It is much faster to first make changes, and THEN set up derived views.

The last issue is very similar to updating indexes in a classical database. It may in fact be more effective to drop derived views and then rebuild them when a lot of changes are going to be made to an underlying view.  Projections are not affected, only sorts and - to a lesser degree - selections.


Where to define properties

Properties are lightweight objects in MetaKit.

In plain english this means that it is not very expensive to create objects with any of the predefined property classes.  In fact, a property is more or less just a symbol table entry with a unique ID.

What this means is that you can use properties in several different ways. The simplest way is to declare all the properties you need as global objects (or as static class members perhaps). Properties do not represent data, they represent the name and type of the fields which can be used to work WITH the data.  This is very similar to class definitions in C++ - class members are defined in headers, whereas the actual data (the objects) are constructed at run time.

Because properties are so easy to construct on the fly, you can also embed them into a class:

.   class MyClass

.   {

.       ...

.       c4_StringProp pName;

.       c4_IntProp pAge;

.       ...

.   };

.

.   MyClass::MyClass ()

.     : ... pName ("name"), pAge ("age") ...

.   { }

All members of the class can work with these properties when they need them, just as if they were global, but this approach allows you to avoid global variables altogether.

Note that you can pass c4_View objects around in your code even though the properties mentioned in it are no longer present as objects (i.e. when the MyClass object has been destroyed).  To access a specific property in such a c4_View object, you can simply create a new c4_xxxProp instance - as a temporary on the stack even.  Even if properties are declared more than once, they will all represent the same thing.

The c4_xxxProp classes are only glue for C++.  Data which is contained in views (or stored on file) is not dependent on whether a property object for it exists. This is what makes it possible to load any datafile, even if the views stored in it contain properties which are not known to the application. This mechanism is essential to be able to write generic datafile viewers, etc.

For maximum performance, you should still keep property declarations out of inner loops, though.


CONFIG.H - Wrapper for the compatibility headers
Module CONFIG.H - Wrapper for the compatibility headers

Filename: C:/JC/PROJ/MK/SRC/CONFIG.H

Description

This file wraps all machine dependencies and compiler dependent stuff.

Copyright ©  1996 Meta Four Software. All rights reserved.


CONFWM.H - Public Windows/MFC configuration header
Module CONFWM.H - Public Windows/MFC configuration header

Filename: C:/JC/PROJ/MK/INCLUDE/K4CONFWM.H

Description

This is the simplified header (Windows/MFC only) for use with MetaKit.

There is no point in exporting the bulky and complex conditional header structure used within the library itself, but the definitions below will have to be changed substantially to support other platforms, etc.

Copyright ©  1996 Meta Four Software. All rights reserved.


DEFS.H - Set up the "q4_*" defines
Module DEFS.H - Set up the "q4_*" defines

Filename: C:/JC/PROJ/MK/SRC/DEFS.H

Description

The task of this file is to figure out what each compiler environment is trying to tell us through its predefined constants, either from the pre- processor or from the IDE.  Configuration choices should go in "fix.h".

Copyright ©  1996 Meta Four Software. All rights reserved.


DERIVED.CPP - Derived sequence implementation.
Module DERIVED.CPP - Derived sequence implementation.

Filename: C:/JC/PROJ/MK/SRC/DERIVED.CPP

Description

This file contains the implementation of the derived sequences.

To Do

implement propagation of sort, solve a few complex problems

simplify this stuff, it's becoming far too large...

_rowMap + _revmap use longs, should be shorts on 16-bit machines

the compare function adjusts asc/desc order, even outside sort

Copyright ©  1996 Meta Four Software. All rights reserved.


DERIVED.H - Derived sequences declarations
Module DERIVED.H - Derived sequences declarations

Filename: C:/JC/PROJ/MK/SRC/DERIVED.H

Description

This file contains the declaration of the derived sequences.

Copyright ©  1996 Meta Four Software. All rights reserved.


FIELD.CPP - Field implementation.
Module FIELD.CPP - Field implementation.

Filename: C:/JC/PROJ/MK/SRC/FIELD.CPP

Description

This file contains the implementation of the field classes.

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_Field


FIELD.H - Field declarations
Module FIELD.H - Field declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4FIELD.H

Description

This file contains the declaration of the field classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


FIELD.INL - Field inline declarations
Module FIELD.INL - Field inline declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4FIELD.INL

Description

This file contains inline definitions for the field classes.

Only very small members are selected for inline code. See the class listing for a description of these functions.

Copyright ©  1996 Meta Four Software. All rights reserved.


FIX.H - Header to fix compatibility problems
Module FIX.H - Header to fix compatibility problems

Filename: C:/JC/PROJ/MK/SRC/FIX.H

Description

This is the place to alter the defines which were set up in "defs.h". If necessary, code from "config.h" can be duplicated and adjusted here. By placing all fixes here, future updates will be far easier to install. See "config.h" for further comments on how to use this file.

Copyright ©  1996 Meta Four Software. All rights reserved.


FORMAT.CPP - Format handler implementation.
Module FORMAT.CPP - Format handler implementation.

Filename: C:/JC/PROJ/MK/SRC/FORMAT.CPP

Description

This file contains the implementation of the format handler classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


FORMAT.H - Format handler declarations
Module FORMAT.H - Format handler declarations

Filename: C:/JC/PROJ/MK/SRC/FORMAT.H

Description

This file contains the declaration of the format handler classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


HANDLER.CPP - Data handler implementation.
Module HANDLER.CPP - Data handler implementation.

Filename: C:/JC/PROJ/MK/SRC/HANDLER.CPP

Description

This file contains the implementation of the data handler classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


HANDLER.H - Data handler declarations
Module HANDLER.H - Data handler declarations

Filename: C:/JC/PROJ/MK/SRC/HANDLER.H

Description

This file contains the declaration of the data handler classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


HEADER.H - First header in sources
Module HEADER.H - First header in sources

Filename: C:/JC/PROJ/MK/SRC/HEADER.H

Description

This header file is always the first in each library source file.

Copyright ©  1996 Meta Four Software. All rights reserved.

CONFIG.H - Wrapper for the compatibility headers

DEFS.H - Set up the "q4_*" defines

FIX.H - Header to fix compatibility problems

HEADER.H - First header in sources

MFC.H - Microsoft Foundation Classes

MSVC.H - Microsoft Visual C++

WIN.H - All flavors of Windows and DOS


MFC.CPP - MFC support classes
Module MFC.CPP - MFC support classes

Filename: C:/JC/PROJ/MK/SRC/MFC.CPP

Description

This file contains the implementation of the MFC support classes.

Copyright ©  1993-1996 Meta Four Software. All rights reserved.


MFC.H - Microsoft Foundation Classes
Module MFC.H - Microsoft Foundation Classes

Filename: C:/JC/PROJ/MK/SRC/MFC.H

Description

Specific header for the Microsoft Foundation Classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


MSVC.H - Microsoft Visual C++
Module MSVC.H - Microsoft Visual C++

Filename: C:/JC/PROJ/MK/SRC/MSVC.H

Description

Specific header for the Microsoft Visual C++ development tools.

Copyright ©  1996 Meta Four Software. All rights reserved.


PERSIST.CPP - Persistence implementation.
Module PERSIST.CPP - Persistence implementation.

Filename: C:/JC/PROJ/MK/SRC/PERSIST.CPP

Description

This file contains the implementation of the persistence classes.

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_Persist


PERSIST.H - Persistence declarations
Module PERSIST.H - Persistence declarations

Filename: C:/JC/PROJ/MK/SRC/PERSIST.H

Description

This file contains the declaration of the persistence classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


STORE.CPP - Storage implementation.
Module STORE.CPP - Storage implementation.

Filename: C:/JC/PROJ/MK/SRC/STORE.CPP

Description

This file contains the implementation of the storage classes.

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_Handler


STORE.H - Storage declarations
Module STORE.H - Storage declarations

Filename: C:/JC/PROJ/MK/SRC/STORE.H

Description

This file contains the declaration of the storage classes.

To Do

Updatable views (where appropriate, lots of tricky details).

Copyright ©  1996 Meta Four Software. All rights reserved.


STRAT.H - Strategy declarations
Module STRAT.H - Strategy declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4STRAT.H

Description

This file contains the declaration of the strategy class.

Copyright ©  1996 Meta Four Software. All rights reserved.


TABLE.CPP - Table implementation.
Module TABLE.CPP - Table implementation.

Filename: C:/JC/PROJ/MK/SRC/TABLE.CPP

Description

This file contains the implementation of the table classes.

To Do

Don't load data now from flat format if not necessary.

Commit over flat format is destructive, shouldn't be.

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_Bytes

c4_Column

c4_Table


TABLE.H - Table declarations
Module TABLE.H - Table declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4TABLE.H

Description

This file contains the declaration of the table classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


TABLE.INL - Table inline declarations
Module TABLE.INL - Table inline declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4TABLE.INL

Description

This file contains inline definitions for the table classes.

Only very small members are selected for inline code. See the class listing for a description of these functions.

Copyright ©  1996 Meta Four Software. All rights reserved.


VIEW.CPP - View implementation.
Module VIEW.CPP - View implementation.

Filename: C:/JC/PROJ/MK/SRC/VIEW.CPP

Description

This file contains the implementation of the main view classes.

Views act as a general interface to collections of data objects. Generic "rows" of data can be added, modified, and removed from a view almost like a normal C++ object with a C++ container class.

A major difference between these views and static C++ objects, is that the structure of views can be defined and altered at run time. Access to entries in views is provided by instances of the class c4_Row. Access to the data items in rows is managed by instances of c4_Property. The views themselves are encapsulated by the class c4_View. A reference-counting scheme is used to track the real workhorses of this mechanism, the classes derived from c4_Sequence.

To Do

use binary search for c4_View::Search

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_Cursor

c4_DoubleProp

c4_FloatProp

c4_IntProp

c4_Property

c4_Row

c4_RowRef

c4_Storage

c4_StringProp

c4_View

c4_ViewProp


VIEW.H - View declarations
Module VIEW.H - View declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Description

This file contains the declaration of the main view classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


VIEW.INL - View inline declarations
Module VIEW.INL - View inline declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Description

This file contains inline definitions for the view classes.

Only very small members are selected for inline code. See the class listing for a description of these functions.

Copyright ©  1996 Meta Four Software. All rights reserved.


VIEWX.CPP - Auxiliary View implementation.
Module VIEWX.CPP - Auxiliary View implementation.

Filename: C:/JC/PROJ/MK/SRC/VIEWX.CPP

Description

This file contains the implementation of the auxiliary view classes.

Copyright ©  1996 Meta Four Software. All rights reserved.

c4_DoubleRef

c4_FloatRef

c4_IntRef

c4_Reference

c4_Sequence

c4_StringRef

c4_ViewRef


VIEWX.H - Auxiliary view declarations
Module VIEWX.H - Auxiliary view declarations

Filename: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Description

This file contains the declaration of the auxiliary view classes.

Copyright ©  1996 Meta Four Software. All rights reserved.


WIN.H - All flavors of Windows and DOS
Module WIN.H - All flavors of Windows and DOS

Filename: C:/JC/PROJ/MK/SRC/WIN.H

Description

Specific header for all flavors of Windows and DOS.

Copyright ©  1996 Meta Four Software. All rights reserved.


c4_Bytes (class)
c4_Bytes Class

class c4_Bytes

These fellows know how to clean up their act when they go away.

These objects are used to pass around untyped data without concerns about clean-up. They know whether the bytes need to be de-allocated when these objects go out of scope. Small amounts of data are stored in the object.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4TABLE.H

Class Members

c4_Bytes()

Constructs an empty object.

c4_Bytes(const void*, int)

Constructs an object with contents, no copy.

c4_Bytes(const void*, int, bool)

Constructs an object with contents, optionally as a copy.

c4_Bytes(const c4_Bytes&)

Copy constructor.

~c4_Bytes()

Destructor.

c4_Bytes& operator=(const c4_Bytes&)

Assignment, this may make a private copy of contents.

void Swap(c4_Bytes&)

Swaps the contents and ownership of two byte objects.

int Size() const

Returns the number of bytes of its contents.

const uchar* Contents() const

Returns a pointer to the contents.

uchar* SetBuffer(int)

Defines contents as a freshly allocated buffer of given size.

uchar* SetBufferClear(int)

Allocates a buffer and fills its contents with zero bytes.

friend bool operator==(const c4_Bytes&, const c4_Bytes&)

Returns true if the contents of both objects is equal.

friend bool operator!=(const c4_Bytes&, const c4_Bytes&)

Returns true if the contents of both objects is not equal.


c4_Column (class)
c4_Column Class

class c4_Column

Objects of this class define the column contents of tables.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4TABLE.H

See Also

c4_Table

Class Members

Public members

void SetBuffer(ulong)

Allocate a new buffer of the specified size.

void SetBufferClear(ulong)

Allocate and clear a new buffer of the specified size.

ulong Size() const

Returns the number of bytes as stored on disk.

void SetDirty()

Sets a flag to save this column on commit.

bool IsDirty() const

Returns true if contents needs to be saved.

ulong Position() const

Special access for the DUMP program.

uchar* LoadNow(c4_Persist*, ulong, int* =0)

Make sure the data is loaded into memory.

void Resize(c4_Persist*, ulong, long)

Resize the buffer by inserting or removing space.

bool SaveNow(c4_Streamer&)

Save the buffer if dirty, also writes header.

static void CleanupCache()

Removes spare memory area and deallocates the cache.


c4_Cursor (class)
c4_Cursor Class

class c4_Cursor

A wrapper class of objects to iterate over sequences of rows.

Cursor objects can be used to point to specific entries in a view. A cursor acts very much like a pointer to a row in a view, and is returned when taking the address of a c4_RowRef. Dereferencing a cursor leads to the original row reference again. You can construct a cursor for a c4_Row, but since such rows are not part of a collection, incrementing or decrementing these cursors is meaningless (and wrong).

The usual range of pointer operations can be applied to these objects: pre/post-increment and decrement, adding or subtracting integer offsets, as well as with the full range of comparison operators. If two cursors point to entries in the same view, their difference can be calculated.

As with regular pointers, care must be taken to avoid running off of either end of a view (the debug build includes assertions to check this).

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

c4_Sequence* _seq

Pointer to the sequence.

int _index

Current index into the sequence.

Construction / destruction / dereferencing

c4_Cursor(c4_Sequence&, int)

Constructs a new cursor.

c4_RowRef operator*() const

Dereferences this cursor to "almost" a row.

c4_RowRef operator[](int) const

This is the same as *(cursor + offset).

Stepping the iterator forwards / backwards

c4_Cursor& operator++()

Pre-increments the cursor.

c4_Cursor operator++(int)

Post-increments the cursor.

c4_Cursor& operator--()

Pre-decrements the cursor.

c4_Cursor operator--(int)

Post-decrements the cursor.

c4_Cursor& operator+=(int)

Advances by a given offset.

c4_Cursor& operator-=(int)

Backs up by a given offset.

c4_Cursor operator-(int) const

Subtracts a specified offset.

int operator-(c4_Cursor) const

Returns the distance between two cursors.

friend c4_Cursor operator+(c4_Cursor, int)

Adds specified offset.

friend c4_Cursor operator+(int, c4_Cursor)

Adds specified offset to cursor.

Comparing row positions

friend bool operator==(c4_Cursor, c4_Cursor)

Returns true if both cursors are equal.

friend bool operator!=(c4_Cursor, c4_Cursor)

Returns true if both cursors are not equal.

friend bool operator<(c4_Cursor, c4_Cursor)

True if first cursor is less than second cursor.

friend bool operator>(c4_Cursor, c4_Cursor)

True if first cursor is greater than second cursor.

friend bool operator<=(c4_Cursor, c4_Cursor)

True if first cursor is less or equal to second cursor.

friend bool operator>=(c4_Cursor, c4_Cursor)

True if first cursor is greater or equal to second cursor.


c4_DoubleProp (class)
c4_DoubleProp Class

class c4_DoubleProp: public c4_Property

Class of objects representing double precision properties.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_DoubleProp(const char*)

Constructs a new property.

c4_Row operator[](double)

Creates a row with one double precision value.

c4_DoubleRef operator()(c4_RowRef)

Gets or sets a double precision property of a row.


c4_DoubleProp::c4_DoubleProp

d4_inline c4_DoubleProp::c4_DoubleProp(const char* name_)

Constructs a new double precision property.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

name_

the name of this property


c4_DoubleRef (class)
c4_DoubleRef Class

class c4_DoubleRef: public c4_Reference

Used to get or set double precision values.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

Public members

c4_DoubleRef(const c4_Reference&)

Constructor.

operator double () const

Gets the value as floating point.

c4_DoubleRef& operator=(double)

Sets the value to the specified floating point.


c4_Field (class)
c4_Field Class

class c4_Field

Fields form a tree describing the underlying data structure.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4FIELD.H

Construction / destruction

Class Members

c4_Field(const char*&, c4_Field* =0)

Constructs a new field.

~c4_Field()

Destructor.

Structural information

bool IsRoot() const

Returns true if this is the root field.

c4_Field& Parent() const

returns the field which contains this one.

int Index() const

Returns the index of this field in its parent.

int Level() const

Returns the nesting level of this field.

int Degree() const

Returns the repetition degree of this field.

c4_Field& FindContainer()

Returns the enclosing repeating field.

Repeating and compound fields

int NumSubFields() const

Returns the number of subfields.

c4_Field& SubField(int) const

Returns the description of each subfield.

bool IsRepeating() const

Returns true if this field contains subtables.

int NumSubColumns() const

Returns total number of columns in the subtables.

c4_Field& SubColumn(int) const

Returns the description of each subtable column.

Field name and description

c4_String Name(bool =false) const

Returns name of this field, default omits details.

c4_String Type() const

Returns the type description of this field, if any.

c4_String Tag() const

Returns the fully specified name of this field.

c4_String Description(bool =false) const

Describes the structure, can omit field names.

int FindSubField(const char*) const

Finds the subfield index by name.

Column offsets and counts

int Offset() const

Returns start of the first column in the table.

int Width() const

Returns number of columns used in the table.

int Depth() const

Returns depth to the table containing the data.

int FindIndex(int) const

Finds the field index of a given table column.


c4_FloatProp (class)
c4_FloatProp Class

class c4_FloatProp: public c4_Property

Class of objects representing floating point properties.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_FloatProp(const char*)

Constructs a new property.

c4_Row operator[](double)

Creates a row with one floating point value.

c4_FloatRef operator()(c4_RowRef)

Gets or sets a floating point property of a row.


c4_FloatProp::c4_FloatProp

d4_inline c4_FloatProp::c4_FloatProp(const char* name_)

Constructs a new floating point property.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

name_

the name of this property


c4_FloatRef (class)
c4_FloatRef Class

class c4_FloatRef: public c4_Reference

Used to get or set floating point values.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

Public members

c4_FloatRef(const c4_Reference&)

Constructor.

operator double () const

Gets the value as floating point.

c4_FloatRef& operator=(double)

Sets the value to the specified floating point.


c4_Handler (class)
c4_Handler Class

class c4_Handler

Handlers deal with all issues concerning data representation.

Defined in: C:/JC/PROJ/MK/SRC/STORE.H

Class Members

Public members

c4_Handler()

Constructor.

virtual ~c4_Handler()

Destructor.

virtual void Initialize(c4_HandlerSeq&, int, c4_Property&)

Initializes the data handler once context is known.

virtual void Defined()

Called when the corresponding table has been fully defined.

virtual void FlipBytes()

Called to reverse the internal byte order of foreign data.

int PropId() const

Returns the id of the property associated to this handler.

virtual void Clear(c4_Bytes& buf_)

Returns the default value for items of this type.

virtual void Get(int index_, c4_Bytes& buf_)

Retrieves the data item at the specified index.

virtual void Set(int index_, const c4_Bytes& buf_)

Stores a new data item at the specified index.

virtual int Compare(int index_, const c4_Bytes& buf_)

Compares an entry with a specified data item.

virtual void Insert(int index_, const c4_Bytes& buf_, int count_)

Inserts 1 or more data items at the specified index.

virtual void Remove(int index_, int count_)

Removes 1 or more data items at the specified index.

void Move(int from_, int to_)

Move a data item to another position.


c4_IntProp (class)
c4_IntProp Class

class c4_IntProp: public c4_Property

Class of objects representing integer properties.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_IntProp(const char*)

Constructs a new property.

c4_Row operator[](long)

Creates a row with one integer.

c4_IntRef operator()(c4_RowRef)

Gets or sets an integer property of a row.


c4_IntProp::c4_IntProp

d4_inline c4_IntProp::c4_IntProp(const char* name_)

Constructs a new integer property.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

name_

the name of this property


c4_IntRef (class)
c4_IntRef Class

class c4_IntRef: public c4_Reference

Used to get or set integer values.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

Public members

c4_IntRef(const c4_Reference&)

Constructor.

operator long () const

Gets the value as long integer.

c4_IntRef& operator=(long)

Sets the value to the specified long integer.


c4_Persist (class)
c4_Persist Class

class c4_Persist

These objects manage persistent storage of tables on file.

Defined in: C:/JC/PROJ/MK/SRC/PERSIST.H

Class Members

Public members

c4_Persist(c4_Strategy&, c4_Table* =0, bool =false)

Constructs a new object.

~c4_Persist()

Destructor.

c4_Table* Root() const

Returns the root table of this object.

c4_Strategy& Strategy() const

Returns the file associated with this object.

bool Commit()

Flushes pending changes to file right now.

bool Rollback()

(Re)initializes for on-demand loading. This will cancel any uncommitted changes.

bool Load(void*)

Loads contents from the specified input stream.

bool Save(void*)

Saves contents to the specified output stream.

bool IsForeign() const

Returns true if the file format is not native (bytes flipped).


c4_Property (class)
c4_Property Class

class c4_Property

Properties correspond to the subfields of data rows.

Property objects exist independently of view, row, and storage objects. They have a name and type, and can be used by multiple views. You will normally only use derived classes for strong typing.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

See Also

c4_IntProp, c4_FloatProp, c4_DoubleProp, c4_StringProp, c4_ViewProp

int _id

The id corresponding to this property.

Class Members

Public members

c4_Property(char, const char*)

Constructs a new property with the give type and name.

c4_Property(int)

Constructs a property from its id.

~c4_Property()

Destructor.

c4_Property(const c4_Property&)

Copy constructor.

void operator=(const c4_Property&)

Assignment.

c4_String Name() const

Returns the name of this property.

char Type() const

Returns the type of this property.

int GetId() const

Returns a unique id for this property. Properties with the same type and name always share the same id.

c4_Reference operator()(c4_RowRef) const

Gets or sets this untyped property in a row.

void Refs(int) const

Adjusts the reference count.

static void CleanupCache()

Removes unused property info and deallocates the cache.


c4_Reference (class)
c4_Reference Class

class c4_Reference

A reference is used to get or set typed data, using derived classes.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

See Also

c4_IntRef, c4_FloatRef, c4_DoubleRef, c4_StringRef, c4_ViewRef

c4_Cursor _cursor

The cursor which points to the data.

int _propId

The property id associated to this reference.

Class Members

Public members

c4_Reference(c4_RowRef, int)

Constructor.

c4_Reference& operator=(const c4_Reference&)

Assignment of one data item.

bool GetData(c4_Bytes&) const

Retrieves the value of the referenced data item.

void SetData(const c4_Bytes&) const

Stores a value into the referenced data item.

friend bool operator==(const c4_Reference&, const c4_Reference&)

Returns true if the contents of both references is equal.

friend bool operator!=(const c4_Reference&, const c4_Reference&)

Returns true if the contents of both references is not equal.


c4_Row (class)
c4_Row Class

class c4_Row: public c4_RowRef

A row is an entry in a sequence with copy semantics.

Rows can exist by themselves and as the contents of views. Row assignment implies that a copy of the contents of the originating row is made.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_Row()

Constructs a row with no properties.

c4_Row(const c4_Row&)

Constructs a row from another one.

c4_Row(const c4_RowRef&)

Constructs a row copy from a row reference.

~c4_Row()

Destructor.

c4_Row& operator=(const c4_Row&)

Assigns a copy of another row to this one.

c4_Row& operator=(const c4_RowRef&)

Copies another row to this one.

void ConcatRow(const c4_RowRef&)

Adds all properties and values into this row.

friend c4_Row operator+(const c4_RowRef&, const c4_RowRef&)

Returns a new row which is the concatenation of two others.


c4_Row::c4_Row

c4_Row::c4_Row()

Default constructor.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP


c4_Row::ConcatRow

void c4_Row::ConcatRow(const c4_RowRef& rowRef_)

Adds all properties and values into this row.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Parameters

rowRef_

the row to concatenate from


c4_Row::operator=

c4_Row& c4_Row::operator=(const c4_RowRef& rowRef_)

Assignment from a reference to a row.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Parameters

rowRef_

the row reference to assign from


c4_Row::~c4_Row

c4_Row::~c4_Row()

Destructor.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP


c4_RowRef (class)
c4_RowRef Class

class c4_RowRef

Row references can be used on either side of an assignment.

Row references are created when dereferencing a c4_Cursor or when indexing an element of a c4_View.  Assignment will change the corresponding item.  Rows (objects of type c4_Row) are a special case of row references, consisting of a view with exactly one item.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

c4_Cursor _cursor

A row reference is a cursor in disguise.

General operations

c4_RowRef operator=(const c4_RowRef&)

Assigns the value of another row to this one.

c4_Cursor operator&() const

Returns the cursor associated to this row.

c4_View Container() const

Returns the underlying container view.

Comparing row contents

friend bool operator==(c4_RowRef, c4_RowRef)

Returns true if the contents of both rows is equal.

friend bool operator!=(c4_RowRef, c4_RowRef)

Returns true if the contents of both rows is not equal.

friend bool operator<(c4_RowRef, c4_RowRef)

True if first row is less than second row.

friend bool operator>(c4_RowRef, c4_RowRef)

True if first row is greater than second row.

friend bool operator<=(c4_RowRef, c4_RowRef)

True if first row is less or equal to second row.

friend bool operator>=(c4_RowRef, c4_RowRef)

True if first row is greater or equal to second row.


c4_Sequence (class)
c4_Sequence Class

class c4_Sequence

A sequence is an abstract base class for views on ranges of records.

Sequences represent arrays of rows (or indexed collections / tables). Insertion and removal of entries is allowed, but can take linear time. A reference count is maintained to decide when the object should go away.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

int _refCount

Reference count.

c4_Dependencies* _dependencies

Pointer to depency list, or null if nothing depends on this.

int _lastPropIndex

Optimization: cached property index.

public:

Optimization: cached property id. see c4_HandlerSeq::Reset()

General

c4_Sequence()

Abstract constructor.

virtual int Compare(int, c4_Cursor) const

Compares the specified row with another one.

void SetAt(int, c4_Cursor)

Replaces the contents of a specified row.

virtual int RemapIndex(int, const c4_Sequence*) const

Remaps the index to an underlying view.

c4_String Describe() const

Returns a descriptions of the current data structure.

Reference counting

void IncRef()

Increments the reference count of this sequence.

void DecRef()

Decrements the reference count, delete objects when last.

int NumRefs() const

Returns the current number of references to this sequence.

Adding / removing rows

virtual int Size() const

Returns the current number of rows.

void Resize(int, int =-1)

Changes number of rows, either by inserting or removing them.

virtual void InsertAt(int, c4_Cursor, int =1)

Inserts one or more rows into this sequence.

virtual void RemoveAt(int, int =1)

Removes one or more rows from this sequence.

virtual void Move(int, int)

Move a row to another position.

Properties

virtual int NthProperty(int) const

Returns the id of the N-th property.

int PropIndex(int, bool =false)

Finds the index of a property, or creates a new entry.

virtual int NumHandlers() const

Returns the number of data handlers in this sequence.

virtual c4_Handler& NthHandler(int) const

Returns a reference to the N-th handler in this sequence.

virtual const c4_Sequence* HandlerContext(int) const

Returns the context of the N-th handler in this sequence.

virtual int AddHandler(c4_Property&, c4_Handler*)

Adds the specified data handler to this sequence.

Element access

virtual bool Get(int, int, c4_Bytes&)

Retrieves one data item from this sequence.

virtual void Set(int, int, const c4_Bytes&)

Stores a data item into this sequence.

Dependency notification

void Attach(c4_Sequence* child_)

Registers a sequence to receive change notifications.

void Detach(c4_Sequence* child_)

Unregisters a sequence which received change notifications.

c4_Dependencies* GetDependencies() const

Returns a pointer to the dependencies, or null.

virtual c4_Notifier* PreChange(c4_Notifier& nf_)

Called just before a change is made to the sequence.

virtual void PostChange(c4_Notifier& nf_)

Called after changes have been made to the sequence.


c4_Storage (class)
c4_Storage Class

class c4_Storage

Objects of this class manage persistent storage of view structures.

The storage class uses a view, with additional functionality to be able to store and reload the data it contains (including nested subviews).

By default, data is loaded on demand, i.e. whenever data which has not yet been referenced is used for the first time. Loading is limited to the lifetime of this storage object, since the storage object carries the file descriptor with it that is needed to access the data file.

To save changes, call the Commit member. This is the only time that data is written to file - when using a read-only file simply avoid calling Commit.

The LoadFromStream and SaveToStream members can be used to serialize the contents of this storage row using only sequential I/O (no seeking, only read or write calls).

The data storage mechanism implementation provides fail-safe operation: if anything prevents Commit from completing its task, the last succesfully committed version of the saved data will be recovered on the next open. This also includes changes made to the table structure.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Example

The following code creates a view with 1 row and stores it on file:

c4_StringProp pName ("Name");

c4_IntProp pAge ("Age");

c4_Storage storage ("myfile.dat", true);

c4_View myView;

myView.Add(pName ["John Williams"] + pAge [43]);

storage.Store("Musicians", myView);

storage.Commit();

c4_Persist* _persist

Pointer to the persistence implementation.

c4_Strategy* _cleanup

Non-zero of the strategy object is owned by this storage.

bool _keepFile

True is the file object is NOT owned by this storage.

c4_String _structure

A description of the current structure.

Class Members

Public members

c4_Storage(c4_File* =0)

Constructs streaming-only or descriptor-based storage object.

c4_Storage(c4_Strategy&)

Constructs a storage using the specified strategy handler.

c4_Storage(const char*, const char*)

Constructs a storage object for given file and format.

c4_Storage(const char*, bool canModify_)

Constructs a storage object, keeping the current structure.

~c4_Storage()

Destructor.

c4_RowRef Contents() const

Gives access to the stored data as a single row.

c4_Strategy& Strategy() const

Returns the strategy object associated with this storage.

c4_Table& RootTable() const

Returns the root table entry.

c4_String Description() const

Returns a description of the data structure.

bool Commit()

Flushes pending changes to file right now.

bool Rollback()

(Re)initializes for on-demand loading. This will cancel any uncommitted changes.

c4_ViewRef View(const char* name_) const

Used to get or set a named view in this storage object.

c4_View GetAs(const char* description_)

Get a named view, redefining it to match the given structure.

c4_View Store(const char* name_, const c4_View& view_)

Attaches a view using specified name in this storage object.

void LoadFromStream(void*)

Loads contents from the specified input stream.

void SaveToStream(void*)

Saves contents to the specified output stream.


c4_Storage::c4_Storage

Constructs a new storage object.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Syntax

c4_Storage::c4_Storage (c4_File* file_ =0);

c4_Storage::c4_Storage (c4_Strategy& strategy_);

c4_Storage::c4_Storage (const char* fname_, const char* desc_);

c4_Storage::c4_Storage (const char* fname_, bool rw_);

Parameters

strategy_

the strategy object

fname_

the file name

desc_

a description of the data structure

rw_

true if data can be modified

file_

pointer to the file object


c4_Storage::Commit

bool c4_Storage::Commit()

Flushes any pending changes to file right now.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Return Value

Describes commit actions taken:

true

There were changes, which have been saved to file.

false

There was nothing to commit, call ignored.


c4_Storage::Contents

c4_RowRef c4_Storage::Contents()

Gives access to the stored data as a single row.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Return Value

Returns a reference to the entire row of the root table.


c4_Storage::LoadFromStream

void c4_Storage::LoadFromStream(void* arg_)

Loads contents from the specified input stream.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Parameters

arg_

the stream to read serialized data from


c4_Storage::Rollback

bool c4_Storage::Rollback()

(Re)initialize for on-demand loading.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Return Value

Describes rollback action taken:

true

Everything was committed, no changes were discarded.

false

Rolled back one or more uncommitted changes.


c4_Storage::SaveToStream

void c4_Storage::SaveToStream(void* arg_)

Saves contents to the specified output stream.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Parameters

arg_

the stream to read serialized data from


c4_Storage::Store

c4_View c4_Storage::Store(const char* name_, const c4_View& view_)

Stores a view under a specified name in this storage object.

Defined in: C:/JC/PROJ/MK/SRC/STORE.CPP

Parameters

name_

the name of the view property to set

view_

the view to be stored


c4_Storage::View

d4_inline c4_ViewRef c4_Storage::View(const char* name_)

Used to get or set a named view in this storage object.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

Returns a reference to the specified view.

Parameters

name_

the name of the view property to use


c4_Strategy (class)
c4_Strategy Class

class c4_Strategy

A strategy encapsulates code dealing with file I/O and the system.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4STRAT.H

Class Members

Public members

c4_Strategy()

Constructs a new strategy object.

virtual ~c4_Strategy()

Destructor.

virtual bool DataOpen(const char*, bool)

Open a data file by name.

virtual void DataSeek(long)

Set file position.

virtual int DataRead(void*, int)

Read a number of bytes.

virtual void DataLoad(void*, int)

Read an exact number of bytes.

virtual void DataWrite(const void*, int)

Write a number of bytes.

virtual void DataCommit(long)

Flush and truncate file.

virtual int StreamRead(void*, void*, int)

Consume some bytes sequentially.

virtual void StreamWrite(void*, const void*, int)

Produce some bytes sequentially.

Protected members

c4_File* _file

Pointer to file object.


c4_StringProp (class)
c4_StringProp Class

class c4_StringProp: public c4_Property

Class of objects representing string properties.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_StringProp(const char*)

Constructs a new property.

c4_Row operator[](const char*)

Create a row with one string.

c4_StringRef operator()(c4_RowRef)

Gets or sets a string property of a row.


c4_StringProp::c4_StringProp

d4_inline c4_StringProp::c4_StringProp(const char* name_)

Constructs a new string property.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

name_

the name of this property


c4_StringRef (class)
c4_StringRef Class

class c4_StringRef: public c4_Reference

Used to get or set string values.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

Public members

c4_StringRef(const c4_Reference&)

Constructor.

operator c4_String () const

Gets the value as string.

c4_StringRef& operator=(const char*)

Sets the value to the specified string.


c4_Table (class)
c4_Table Class

class c4_Table

Tables organize the data and know their own structure and context.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4TABLE.H

Construction / destruction / initialization

Class Members

c4_Table()

Constructs a new object.

~c4_Table()

Destructor.

void DefineRoot(const char*, c4_Persist* =0)

Initializes this table as a root table.

void DefineSub(c4_Field&, c4_Table&, int)

Initializes this table as a nested table.

void Restructure(c4_Field&)

Restructures a table to match the given field layout.

Table properties

c4_Persist* Persist() const

Returns the associated storage, if any.

c4_Field& Definition() const

Returns the repeating field definition.

c4_Table& Owner() const

Returns a reference to the owner of this table.

int OwnerRow() const

Returns the row index in the owning table.

int OwnerColumn() const

Returns the column index in the owning table.

Table dimensions

int NumRows() const

Returns the number of rows in this table.

int NumColumns() const

Returns the number of columns in this table.

Access to subfields

c4_Field& Field(int) const

Returns the field definition of a subcolumn.

c4_Column& Column(int) const

Returns a specific columns of this table.

bool IsNested(int) const

Returns true if a column consists of subtables.

c4_Table& SubTable(int, int)

Returns the N-th subtable of a subcolumn, creates if necessary.

Table persistence

bool Commit(c4_Streamer&, int =0)

Saves current table state to file.

void Prepare(c4_Streamer&)

Loads table state from file.

uchar* LoadColumn(int, ulong, int&) const

Loads one column on demand.

void ResizeColumn(int, ulong, int) const

Resizes one column.

Internal methods

void SetNumRows(int)

Sets the row count internally.

void FixOwnerRows(int, int)

Adjust owner references.

void FlipAllBytes()

Permanently switch the byte orde.

c4_HandlerSeq& Sequence()

Returns a reference to the associated sequence.

void ReplaceEntry(int colNum_, int index_, c4_Sequence* seq_)

Replaces the specified subentry with a new sequence.


c4_View (class)
c4_View Class

class c4_View

A general class of objects to represent a collection of data rows.

Views act like pointers to the actual collections, setting a view to a new value does not alter the collection to which this view pointed previously.

The protocol used for this class mimics the way many other collection classes are defined. For example, when used with MFC, you will see member definitions such as GetSize, GetAt, InsertAt, etc.

The elements of views can be referred to by their 0-based index, which produces a row-reference of type c4_RowRef. These row references can be copied, used to get or set properties, or dereferenced (in which case an object of class c4_Row is returned). Taking the address of a row reference produces a c4_Cursor, which acts very much like a pointer.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Example

The following code creates a view with 1 row and 2 properties:

c4_StringProp pName ("Name");

c4_IntProp pAge ("Age");

//

c4_Row data;

pName (data) = "John Williams";

pAge (data) = 43;

//

c4_View myView;

myView.Add(row);

Class Members

c4_Sequence* _seq

Pointer to the sequence implementation.

Construction / destruction / assignment

c4_View(c4_Sequence* =0)

Constructs a view based on a sequence.

c4_View(const c4_Property&)

Constructs an empty view with one property.

c4_View(const c4_View&)

Constructs a view from another one.

~c4_View()

Destructor.

c4_View& operator=(const c4_View&)

Makes this view the same as another one.

Getting / setting the number of rows

int GetSize() const

Returns the number of entries.

int GetUpperBound() const

Returns highest index (size - 1).

void SetSize(int, int =-1)

Changes the size of this view.

void RemoveAll()

Removes all entries (sets size to zero).

Getting / setting individual elements

c4_RowRef GetAt(int) const

Returns a reference to specified entry.

c4_RowRef operator[](int) const

Shorthand for GetAt.

void SetAt(int, c4_RowRef)

Changes the value of the specified entry.

c4_RowRef ElementAt(int)

Element access, for use as RHS or LHS.

These can increase the number of rows

void SetAtGrow(int, c4_RowRef)

Sets an entry, growing the view if needed.

int Add(c4_RowRef)

Adds a new entry at the end.

Insertion / deletion of rows

void InsertAt(int, c4_RowRef, int =1)

Inserts one or more copies of an entry.

void RemoveAt(int, int =1)

Removes entries starting at the given index.

void InsertAt(int, const c4_View&)

Inserts a copy of the contents of another view.

Dealing with the properties of this view

int NumProperties() const

Returns the number of properties.

int NthProperty(int) const

Returns the id of the N-th property.

int FindProperty(int)

Finds the index of a property, given its id.

Structural information

c4_View Structure() const

Returns a view which describes the structure of this view.

static c4_String Description(const c4_View&)

Returns a homogenized description of this view.

c4_String Describe() const

Returns a description of the structure.

friend c4_View operator,(const c4_View&, const c4_Property&)

Returns a view like the first, with a property appended to it.

Derived views

c4_View Sort() const

Creates view with all rows in natural (property-wise) order.

c4_View SortOn(const c4_View&) const

Creates view sorted according to the specified properties.

c4_View SortOnReverse(const c4_View&, const c4_View&) const

Creates sorted view, with some properties sorted in reverse.

c4_View Select(c4_RowRef) const

Creates a view with rows matching the specified value.

c4_View SelectRange(c4_RowRef, c4_RowRef) const

Creates a view with row values within the specified range.

c4_View Project(const c4_View&) const

Creates a view with the specified property arrangement.

c4_View ProjectWithout(const c4_View&) const

Creates a derived view with some properties omitted.

int GetIndexOf(c4_RowRef) const

Returns the index of the specified row in this view (or -1).

Searching

int Find(c4_RowRef, int start_ =0) const

Finds index of the the next entry matching the specified key.

int Search(c4_RowRef) const

Searches for key, assuming the view is sorted accordingly.


c4_View::Add

int c4_View::Add(c4_RowRef newElem_)

Adds a new entry at the end.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Parameters

newElem_

the element to add


c4_View::c4_View

Constructs a new view object.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Syntax

c4_View::c4_View (c4_Sequence* seq_ =0);

c4_View::c4_View (const c4_Property& prop_);

c4_View::c4_View (const c4_View& view_);

Parameters

prop_

the property

view_

source for copy constructor

seq_

the sequence


c4_View::Description

c4_String c4_View::Description()

Converts a structure view to the equivalent description string.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

A homogenized description of this view.


c4_View::ElementAt

d4_inline c4_RowRef c4_View::ElementAt(int index_)

Element access, for use as RHS or LHS. Shorthand for GetAt().

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A reference to the specified row in the view.

Parameters

index_

the zero-based row index


c4_View::Find

int c4_View::Find(c4_RowRef crit_, int start_ = )

Finds index of the next entry matching the specified key, using linear search. Only the properties present in the search key are used to determine whether a row matches the key.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

Returns the index if found, else -1.

Parameters

crit_

the value to look for

start_

the index to start with


c4_View::FindProperty

d4_inline int c4_View::FindProperty()

Finds a property, given its id, as returned by NthProperty().

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

The index of the property, or -1 of it was not found.


c4_View::GetAt

d4_inline c4_RowRef c4_View::GetAt(int index_)

Returns a reference to specified entry.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A reference to the specified row in the view.

Parameters

index_

the zero-based row index


c4_View::GetIndexOf

int c4_View::GetIndexOf(c4_RowRef& row_)

Returns the index of the specified row in this view (or -1). This function can be used to "unmap" an index of a derived view back to the original underlying view.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The index of the specified row in this, or -1 of not found.

Parameters

row_

the row to relate to this view


c4_View::GetSize

d4_inline int c4_View::GetSize()

Returns the number of entries in this view.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A non-negative integer.


c4_View::GetUpperBound

d4_inline int c4_View::GetUpperBound()

Returns the highest index in this view (same as: GetSize() - 1).

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

One less than the number of entries. If there are no entries, the value -1 is returned.


c4_View::InsertAt

d4_inline void c4_View::InsertAt(int index_, c4_RowRef newElem_, int count_ = 1)

Inserts one or more copies of an entry. This is identical to inserting the specified number of default entries and then setting each of them to the new element value passed as argument.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

index_

the zero-based row index

newElem_

the value to insert

count_

the number of entries to insert


c4_View::InsertAt

void c4_View::InsertAt()

Inserts a copy of the contents of another view.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP


c4_View::NthProperty

d4_inline int c4_View::NthProperty(int index_)

Returns the N-th property (using zero-based indexing).

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A reference to the specified property.

Parameters

index_

the zero-based property index


c4_View::NumProperties

d4_inline int c4_View::NumProperties()

Returns the number of properties present in this view.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A non-negative integer.


c4_View::operator=

c4_View& c4_View::operator=(const c4_View& view_)

Makes this view the same as another one.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Parameters

view_

the view to use as source


c4_View::operator[]

d4_inline c4_RowRef c4_View::operator[](int index_)

Shorthand for GetAt.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Return Value

A reference to the specified row in the view. This reference can be used on either side of the assignment operator.

Parameters

index_

the zero-based row index


c4_View::Project

c4_View c4_View::Project(const c4_View& in_)

Creates a view with the specified property arrangement.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

in_

the properties included in the result


c4_View::ProjectWithout

c4_View c4_View::ProjectWithout(const c4_View& out_)

Creates a view with the specified property arrangement.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

out_

the properties excluded from the result


c4_View::RemoveAll

d4_inline void c4_View::RemoveAll()

Removes all entries (sets size to zero).

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL


c4_View::RemoveAt

d4_inline void c4_View::RemoveAt(int index_, int count_ = 1)

Removes entries starting at the given index. Entries which have other view references may cause these views to be deleted if their reference counts drop to zero because of this removal.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

index_

the zero-based row index

count_

the number of entries to remove


c4_View::Search

int c4_View::Search(c4_RowRef crit_)

Searches for a key, assuming the view is sorted accordingly. The current version is not very efficient, since it does not take advantage of the fact that the view is sorted (no binary search yet).

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

Returns index of first row >= crit_, else indexes past the end.

Parameters

crit_

the value to look for


c4_View::Select

c4_View c4_View::Select(c4_RowRef crit_)

Creates a view with rows matching the specified value.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

crit_

the values determining which row to select


c4_View::SelectRange

c4_View c4_View::SelectRange(c4_RowRef low_, c4_RowRef high_)

Creates a view with row values within the specified range.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

low_

the values of the lower bounds (inclusive)

high_

the values of the upper bounds (inclusive)


c4_View::SetAt

d4_inline void c4_View::SetAt(int index_, c4_RowRef newElem_)

Changes the value of the specified entry. If the new value has other properties, these will be added to the underlying view.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

index_

the zero-based row index

newElem_

the row to copy to this view


c4_View::SetAtGrow

void c4_View::SetAtGrow(int index_, c4_RowRef newElem_)

Sets an entry, growing the view if needed.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Parameters

index_

the position of the new entry

newElem_

the element to copy into this view


c4_View::SetSize

d4_inline void c4_View::SetSize(int newSize_, int growBy_ = -1)

Changes the size of this view.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

newSize_

the new size of this view

growBy_

the granularity of size increases (not used)


c4_View::Sort

c4_View c4_View::Sort()

Creates view with all rows in natural (property-wise) order.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.


c4_View::SortOn

c4_View c4_View::SortOn(const c4_View& up_)

Creates view sorted according to the specified properties.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

up_

the view which defines the sort order


c4_View::SortOnReverse

c4_View c4_View::SortOnReverse(const c4_View& up_, const c4_View& down_)

Creates sorted view, with some properties sorted in reverse.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The derived view, based on the rows of the underlying one.

Parameters

up_

the view which defines the sort order

down_

subset of up_, defines reverse order


c4_View::Structure

c4_View c4_View::Structure()

Scans this view to determine its structure.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

The meta-view which describes the structure of this view.


c4_View::~c4_View

d4_inline c4_View::~c4_View()

Destructor.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL


c4_ViewProp (class)
c4_ViewProp Class

class c4_ViewProp: public c4_Property

Class of objects representing view properties.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.H

Class Members

Public members

c4_ViewProp(const char*)

Constructs a new property.

c4_Row operator[](const c4_View&)

Create a row with one view.

c4_ViewRef operator()(c4_RowRef)

Gets or sets a view property of a row.


c4_ViewProp::c4_ViewProp

d4_inline c4_ViewProp::c4_ViewProp(const char* name_)

Constructs a new view property.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEW.INL

Parameters

name_

the name of this property


c4_ViewRef (class)
c4_ViewRef Class

class c4_ViewRef: public c4_Reference

Used to get or set view values.

Defined in: C:/JC/PROJ/MK/INCLUDE/K4VIEWX.H

Class Members

Public members

c4_ViewRef(const c4_Reference&)

Constructor.

operator c4_View () const

Gets the value as view.

c4_ViewRef& operator=(const c4_View&)

Sets the value to the specified view.


operator

c4_View operator()

Defines a column for a property. This operator is a shorthand for FindProperty with the mayAdd_ parameter set to true.

Defined in: C:/JC/PROJ/MK/SRC/VIEW.CPP

Return Value

This object.

Example

The following code defines an empty view with three properties:

c4_IntProp p1, p2, p3;

c4_View myView = (p1, p2, p3);

See Also

c4_Property